feat: chain orchestrator #185

frisitano · 2025-07-02T19:06:49Z

closes: #182
closes scroll-tech/reth#243

Copilot

Pull Request Overview

This PR implements a new ChainOrchestrator to replace the previous indexer, integrates it throughout the node, watcher, network, and engine, and updates tests and database migrations accordingly.

Introduces ChainOrchestrator in place of Indexer, refactors RollupNodeManager to consume orchestrator events instead of indexer events.
Adds Synced notifications to L1Watcher and updates engine driver to handle optimistic sync via ChainOrchestrator.
Refactors configuration (ScrollRollupNodeConfig), network manager, and database migrations; adjusts tests to cover the new orchestrator flows.

Reviewed Changes

Copilot reviewed 40 out of 41 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
crates/indexer/src/lib.rs	Rename `Indexer` to `ChainOrchestrator` and overhaul API flows
crates/manager/src/manager/mod.rs	Replace indexer usage with `ChainOrchestrator` in node manager
crates/node/src/args.rs	Instantiate `ChainOrchestrator` in `ScrollRollupNodeConfig`
crates/watcher/src/lib.rs	Add `Synced` variant and `is_synced` flag to `L1Watcher`
crates/scroll-wire/src/protocol/proto.rs	Adjust doc comment for `NewBlock::new`
crates/node/tests/e2e.rs	Add/revise reorg and sync end-to-end tests
crates/watcher/tests/reorg.rs	Update tests to skip `Synced` notifications
crates/database/db/src/operations.rs	Extend DB ops with `L1MessageStart` and block-and-batch queries
crates/database/migration/src/migration_info.rs	Add `genesis_hash()` to migrations and insert genesis blocks
crates/network/src/manager.rs	Wire up eth-wire listener and dispatch chain-orchestrator events
crates/engine/src/driver.rs	Support `ChainImport` and `OptimisticSync` futures in engine driver

Comments suppressed due to low confidence (2)

crates/scroll-wire/src/protocol/proto.rs:33

The doc comment uses "blocks" (plural) but the constructor takes a single block; change to "block" for accuracy.

    /// Returns a [`NewBlock`] instance with the provided signature and blocks.

crates/node/tests/e2e.rs:95

The follower_can_reorg test has no assertions; either add meaningful checks or remove the empty test to maintain coverage.

async fn follower_can_reorg() -> eyre::Result<()> {

crates/watcher/tests/reorg.rs

greged93

reviewing l2geth code, I noticed we might be missing checks on L1 messages.

crates/chain-orchestrator/src/lib.rs

greged93

just need to resolve the pending comments and open 1 issues related to L1 watcher sync.

crates/chain-orchestrator/src/event.rs

crates/database/migration/src/migration_info.rs

crates/node/src/args.rs

crates/network/src/manager.rs

crates/manager/src/manager/mod.rs

crates/database/db/src/models/l2_block.rs

crates/scroll-wire/src/protocol/proto.rs

jonastheis · 2025-08-19T02:15:26Z

crates/watcher/src/lib.rs

-            if self.is_synced() {
+            if self.is_synced {
                tokio::time::sleep(SLOW_SYNC_INTERVAL).await;
+            } else if self.current_block_number == self.l1_state.head {
+                // if we have synced to the head of the L1, notify the channel and set the
+                // `is_synced`` flag.
+                if let Err(L1WatcherError::SendError(_)) = self.notify(L1Notification::Synced).await
+                {
+                    tracing::warn!(target: "scroll::watcher", "L1 watcher channel closed, stopping the watcher");
+                    break;
+                }
+                self.is_synced = true;


Agree let's address this in another PR

crates/engine/src/driver.rs

jonastheis · 2025-08-19T05:46:06Z

crates/chain-orchestrator/src/lib.rs

+                let parent_hash =
+                    optimistic_headers.first().expect("chain can not be empty").parent_hash;
+                let header = network_client
+                    .get_header(BlockHashOrNumber::Hash(parent_hash))


This will request up to 2000 headers (by default == CHAIN_BUFFER_SIZE) one by one from other nodes. Is this efficient? Shoudldn't we use GetBlockHeaders for this? Or why request the headers at all? We could also wait for the EN to finish the sync and then load from our EN?

Is this efficient? Shouldn't we use GetBlockHeaders for this?

Yes, a more efficient means would be to use GetBlockHeaders.

We could also wait for the EN to finish the sync and then load from our EN?

I think this is the best solution.

I will add both of these points to the refactoring issue that I create shortly.

jonastheis · 2025-08-19T05:53:33Z

crates/chain-orchestrator/src/lib.rs

+        // Check if we have already have this block in memory.
+        if received_block.number <= max_block_number &&
+            received_block.number >= min_block_number &&
+            current_chain_headers.iter().any(|h| h == &received_block.header)


How expensive is this? Do we expect this to become a bottleneck with high throughput?

I think we can improve the implementation to be much more efficient by leveraging the EN. I think we can completely eliminate the in-memory buffer which should make this solution much more efficient. I will write this up in the issue.

crates/chain-orchestrator/src/lib.rs

crates/node/src/constants.rs

crates/chain-orchestrator/src/lib.rs

jonastheis · 2025-08-19T06:26:06Z

crates/chain-orchestrator/src/lib.rs

+                return Err(ChainOrchestratorError::L2SafeBlockReorgDetected);
+            }
+
+            tracing::trace!(target: "scroll::chain_orchestrator", number = ?(received_chain_headers.last().expect("chain can not be empty").number - 1), "fetching block");


can't we store received_chain_headers.last() in a variable somewhere to avoid calling the expect dozens of times?

jonastheis · 2025-08-19T06:32:48Z

crates/chain-orchestrator/src/lib.rs

+                // If the received fork is older than the current chain, we return an event
+                // indicating that we have received an old fork.
+                if (pos < current_chain_headers.len() - 1) &&
+                    current_chain_headers.get(pos + 1).expect("chain can not be empty").timestamp >


This seems like quite important: we don't react to reorgs based on timestamp of a block. what if the sequencer's time is faulty?

Agree that this is important. What do you think the rule should be?

Not sure what it should be. For now it's okay like this, but we should discuss it. Maybe best to capture in an issue so we can revisit if necessary and don't forget

crates/chain-orchestrator/src/lib.rs

jonastheis · 2025-08-25T08:44:06Z

crates/network/src/manager.rs

-            };
-            self.inner_network_handle().eth_wire_announce_block(eth_wire_new_block, hash);
-        }
+        let eth_wire_new_block = {


why do we actually need to compute the total difficulty here? isn't it part the block header already? eth_wire_block.header.difficulty or is this a different difficulty?

I believe that's the block difficulty and not the total difficulty?

ah yeah you're right I confused it with totalDifficulty which is also returned from API. It's a computed value and our computation is simplified since we have the fixed offset.

cast block --rpc-url https://rpc.scroll.io latest baseFeePerGas 120008 difficulty 1 extraData 0x gasLimit 20000000 gasUsed 266502 hash 0xa5c5ceda288f430b5ac8ccf27c7c8646f54aa299a0fde0689b80d365bfc65286 logsBloom 0x0000008000000000000000000000000000020000000000000000000000000000040000000000000000000001000000000000600000002000000200000000000000000000000000080000000800000000000000004000000420000000000200000000002000100000000000000000000002000000004000000000001000080000000000000000000000000000000000000000006000020040000000000000000000000000000000000000000400000000002000000000000000008000000000200000000200000000000010000000000000040000000000020000000000000000000000000000000200000000000000000000000000008000000000000a000000 miner 0x0000000000000000000000000000000000000000 mixHash 0x0000000000000000000000000000000000000000000000000000000000000000 nonce 0x0000000000000000 number 20063317 parentHash 0x0f8160698ab23ebf35154115bace014f19bf8658ed8c84bbfe1dcd0ac3fdd823 parentBeaconRoot transactionsRoot 0x66043dba38623338f7e845a00709339ca82dd715e46117c73a1ef957d1125548 receiptsRoot 0x4285fb1b3cf957fe86f734635a3fa26901d24c9894930957282727cee3c9f790 sha3Uncles 0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347 size 766 stateRoot 0x6ece91f3f6c025928c08cf1a6abfae4aec074694b4125dc6703504cb0e40a3d7 timestamp 1756111046 (Mon, 25 Aug 2025 08:37:26 +0000) withdrawalsRoot totalDifficulty 34970277 blobGasUsed excessBlobGas requestsHash transactions: [ 0xb2f7bf405118615de93d0834cb0cecd6dc7516d708fad959c9ba39feaf5a1d88 ]

frisitano · 2025-08-25T11:50:06Z

Tests are passing fine locally - I suspect there is some form of content in CI. Will merge and fix later.

frisitano added 12 commits July 2, 2025 19:44

feat: chain orchestrator

c1e5cc2

Merge branch 'main' into feat/chain-orchestrator

bbe0e8f

lint

4032fa5

lint

39802e2

docs lint

c84dc0d

fix: clone the in-memory chain instead of taking it

ea3140c

Merge branch 'main' into feat/chain-orchestrator

a28a5b2

update chain consolidation and l1 message validation

fa6952c

add missing network block error

43cc2be

update fork sync / reconcilliation to use network as opossed to database

5dfc813

Merge branch 'main' into feat/chain-orchestrator

a50558d

fix merege

19458f7

frisitano mentioned this pull request Jul 15, 2025

[ChainOrchestrator] Monitor performance of recursive syncing of blocks #199

Open

frisitano added 2 commits July 16, 2025 12:56

refactor and add test cases

4578d49

cleanup

e6248f5

frisitano marked this pull request as ready for review July 16, 2025 14:10

Merge branch 'main' into feat/chain-orchestrator

626e29b

frisitano requested a review from Copilot July 16, 2025 14:13

Copilot AI reviewed Jul 16, 2025

View reviewed changes

crates/watcher/tests/reorg.rs Show resolved Hide resolved

frisitano added 2 commits July 16, 2025 22:21

rename chain orchestrator crate

7a6ebfc

cleanup

7d35185

frisitano requested a review from greged93 July 17, 2025 17:14

frisitano added 7 commits July 18, 2025 18:36

Merge branch 'main' into feat/chain-orchestrator

74fd7b8

remove expect for sequencer in rnm

fe75ed5

sync test

f3bab0d

sync test

56a0ff3

sync test

1320f14

add error handling for missing paylaod id

0fa87fe

remove networking for L1 consolidation sync test

cecbd03

greged93 mentioned this pull request Jul 22, 2025

feat: bump reth #211

Merged

greged93 mentioned this pull request Aug 5, 2025

L1 message validation scroll-tech/reth#243

Closed

frisitano added 2 commits August 7, 2025 00:48

Merge branch 'main' into feat/chain-orchestrator

9f88b5d

merge upstream

9a3339a

greged93 reviewed Aug 7, 2025

View reviewed changes

crates/chain-orchestrator/src/lib.rs Show resolved Hide resolved

refactor

000ade7

This was referenced Aug 11, 2025

L1 live sync message validation (pre Euclid V2) #245

Open

[Manager] Implement budget on future polling #246

Open

frisitano added 2 commits August 11, 2025 19:09

address comments

00d18f2

Merge branch 'main' into feat/chain-orchestrator

2beb7e0

greged93 previously approved these changes Aug 11, 2025

View reviewed changes

jonastheis reviewed Aug 18, 2025

View reviewed changes

jonastheis reviewed Aug 19, 2025

View reviewed changes

crates/chain-orchestrator/src/lib.rs Show resolved Hide resolved

jonastheis reviewed Aug 20, 2025

View reviewed changes

crates/chain-orchestrator/src/lib.rs Show resolved Hide resolved

crates/chain-orchestrator/src/lib.rs Show resolved Hide resolved

crates/chain-orchestrator/src/lib.rs Outdated Show resolved Hide resolved

crates/chain-orchestrator/src/lib.rs Show resolved Hide resolved

address comments

add9933

frisitano dismissed greged93’s stale review via add9933 August 20, 2025 07:42

frisitano added 2 commits August 20, 2025 16:46

Merge branch 'main' into feat/chain-orchestrator

e3d5453

merge changes

4383231

This was referenced Aug 25, 2025

[ChainOrchestrator] Standardise data structures for received_chain_headers and current_chain_headers #268

Closed

[ChainOrchestrator] Refactoring / Improvements #269

Open

jonastheis reviewed Aug 25, 2025

View reviewed changes

frisitano mentioned this pull request Aug 25, 2025

[ChainOrchestrator] L1 queue hash uses L1 block number #270

Open

Merge branch 'main' into feat/chain-orchestrator

1c24765

jonastheis previously approved these changes Aug 25, 2025

View reviewed changes

add migration script

5d9aefb

frisitano dismissed jonastheis’s stale review via 5d9aefb August 25, 2025 09:53

frisitano merged commit aea3c93 into main Aug 25, 2025
14 of 16 checks passed

frisitano deleted the feat/chain-orchestrator branch August 25, 2025 11:50

feat: chain orchestrator #185

feat: chain orchestrator #185

Uh oh!

Conversation

frisitano commented Jul 2, 2025 • edited by greged93 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

greged93 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

greged93 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

frisitano Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

frisitano Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonastheis Aug 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

frisitano commented Aug 25, 2025

Uh oh!

Uh oh!

frisitano commented Jul 2, 2025 •

edited by greged93

Loading

frisitano Aug 20, 2025 •

edited

Loading

frisitano Aug 20, 2025 •

edited

Loading

jonastheis Aug 25, 2025 •

edited

Loading